Piano

Piano subscription data tracks the lifecycle of your subscriptions, from sign-up through renewals, cancellations, and expirations. Download schema (dbt format).

Data Sources

Piano subscription data can be delivered from two sources:

1. Piano API Subscriptions - Current state snapshot of all subscriptions
2. Piano Subscriber Event Stream - Lifecycle events (created, renewed, cancelled, expired, etc.)

We need both sources for complete subscription tracking.

Piano Data Format

We require the dedicated subscription event stream, not Piano Analytics v2 behavioral events. Piano Analytics v2 includes all page views and user interactions with subscription data embedded as properties. For Subsets retention modeling, we need only the subscription lifecycle events in the format described below.

Piano API Subscriptions

Piano API Subscriptions

Field	Type
subscription_id	STRING
user_id	STRING
started_at	TIMESTAMP
billing_period	STRING
subscription_status	STRING
term_type	STRING
regular_price	FLOAT
autorenew	BOOLEAN
autorenew_disabled_at	TIMESTAMP
expiry_reason	STRING

Current state of all subscriptions. This table provides a snapshot view of subscription status, pricing, and renewal settings.

Piano Subscriber Event Stream

Piano Subscriber Event Stream

Field	Type
subscription_id	STRING
user_id	STRING
event_timestamp	TIMESTAMP
subscription_action	STRING
event_name	STRING
resource_name	STRING
next_billed_at	TIMESTAMP
billing_period	STRING
term_type	STRING
term_name	STRING
transaction_value	FLOAT
trial_period_ended_at	TIMESTAMP
trial_duration	STRING
billing_country_code	STRING
subscription_period_number	INTEGER
payment_mode	STRING
upgrade_to_subscription_id	STRING
user_email_hash_sha256	STRING
is_internal_user	BOOLEAN
experience_name	STRING

Lifecycle events tracking subscription changes over time. This append-only log captures all subscription actions and state transitions.

Common subscription_action values:

• Created - New subscription
• Renewed - Successful renewal
• Expired - Subscription ended
• Canceled - Cancellation processed
• TrialStarted - Trial period began
• TrialEnded - Trial period completed
• PaymentFailed - Payment failure
• Upgraded - Plan upgrade
• Downgraded - Plan downgrade
• Resumed - Subscription reactivated
• Auto-renew disabled - Auto-renewal turned off
• Auto-renew enabled - Auto-renewal turned on

Note on term_type filtering: Only payment and dynamic term types are typically used in analytics models. Gift subscriptions and other term types are generally excluded.

Data Filtering

When delivering Piano data, please:

• Exclude test/internal users: Filter out records where is_internal_user = true
• Hash email addresses: Use user_email_hash_sha256 instead of plain email addresses

Data Synchronization

We recommend including:

• Sync timestamp field: A timestamp indicating when the data was synced (e.g., _fivetran_synced, synced_at)
• Timezone normalization: Convert all timestamps to UTC using convert_timezone('UTC', timestamp_field)

Please inform the Subsets team of your partitioning column and sync timestamp field names.

Reference

• Piano API Documentation